<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>ftruncate</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_005_365">&nbsp;</a>NAME</h4><blockquote>
ftruncate, truncate - truncate a file to a specified length
</blockquote><h4><a name = "tag_000_005_366">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="unistd.h.html">unistd.h</a>&gt;

int ftruncate(int <i>fildes</i>, off_t <i>length</i>);
int truncate(const char *<i>path</i>, off_t <i>length</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_005_367">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>ftruncate()</i>
function causes the regular file referenced by <i>fildes</i> to have a size of
<i>length</i> bytes.
<p>
The
<i><a href="truncate.html">truncate()</a></i>
function causes the regular file named by <i>path</i> to have a size of
<i>length</i> bytes.
<p>
If the file previously was larger
than <i>length</i>, the extra data is discarded.  If it was previously shorter
than <i>length</i>, 
it is unspecified whether the file is changed or its size increased.
If the file is extended,
the extended area appears as if it were zero-filled.
If
<i>fildes</i>
references a shared memory object,
<i>ftruncate()</i>
sets the size of the shared memory object to
<i>length</i>.
If the file is not a regular file or a shared memory object,
the result is unspecified.
<p>
With
<i>ftruncate()</i>,
the file must be open for writing; 
for
<i><a href="truncate.html">truncate()</a></i>,
the process must have write permission for the file.
<p>
If the effect of truncation is to decrease the size of a file 
or shared memory object
and whole pages beyond the new end were previously mapped,
then the whole pages beyond the new end will be discarded.
References to the discarded pages result in generation of a
<i>SIGBUS</i>
signal.
<p>
If the request would cause the file size to exceed the soft file size limit
for the process, the request will fail and the implementation will generate
the SIGXFSZ signal for the process.
<p>
These functions do not modify the file offset for any open file descriptions
associated with the file.  On successful completion, if the file size is
changed, these functions will mark for update the
<i>st_ctime</i>
and
<i>st_mtime</i>
fields of the file, and if the file is a regular file, the S_ISUID and S_ISGID
bits of the file mode may be cleared.
</blockquote><h4><a name = "tag_000_005_368">&nbsp;</a>RETURN VALUE</h4><blockquote>
Upon successful completion,
<i>ftruncate()</i>
and
<i><a href="truncate.html">truncate()</a></i>
return 0.  Otherwise a -1 is returned, and <i>errno</i> is set
to indicate the error.
</blockquote><h4><a name = "tag_000_005_369">&nbsp;</a>ERRORS</h4><blockquote>
The
<i>ftruncate()</i>
and
<i><a href="truncate.html">truncate()</a></i>
functions will fail if:
<dl compact>

<dt>[EINTR]<dd>
A signal was caught during execution.

<dt>[EINVAL]<dd>
The <i>length</i> argument was less than 0.

<dt>[EFBIG] or [EINVAL]<dd>

The <i>length</i> argument was greater than the maximum file size.

<dt>[EIO]<dd>
An I/O error occurred while reading from or writing to a file system.

</dl>
<p>
The
<i>ftruncate()</i>
function will fail if:
<dl compact>

<dt>[EBADF] or [EINVAL]<dd>

The <i>fildes</i> argument is not a file descriptor open for writing.

<dt>[EFBIG]<dd>
The file is a regular file and 
<i>length</i>
is greater than the offset
maximum established in the open file description associated with
<i>fildes</i>.

<dt>[EINVAL]<dd>
The <i>fildes</i> argument references a file that was opened without write
permission.

<dt>[EROFS]<dd>
The named file resides on a read-only file system.

</dl>
<p>
The
<i><a href="truncate.html">truncate()</a></i>
function will fail if:
<dl compact>

<dt>[EACCES]<dd>
A component of the path prefix denies search permission, or
write permission is denied on the file.

<dt>[EISDIR]<dd>
The named file is a directory.

<dt>[ELOOP]<dd>
Too many symbolic links were encountered in resolving <i>path</i>.

<dt>[ENAMETOOLONG]<dd>

The length of the specified pathname exceeds PATH_MAX bytes, or the length of
a component of the pathname exceeds NAME_MAX bytes.

<dt>[ENOENT]<dd>
A component of <i>path</i> does not name an existing file
or <i>path</i> is an empty string.

<dt>[ENOTDIR]<dd>
A component of the path prefix of <i>path</i> is not a directory.

<dt>[EROFS]<dd>
The named file resides on a read-only file system.

</dl>
<p>
The
<i><a href="truncate.html">truncate()</a></i>
function may fail if:
<dl compact>

<dt>[ENAMETOOLONG]<dd>

Pathname resolution of a symbolic link produced an intermediate result whose
length exceeds {PATH_MAX}.

</dl>
</blockquote><h4><a name = "tag_000_005_370">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_371">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_372">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_373">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="open.html">open()</a></i>,
<i><a href="unistd.h.html">&lt;unistd.h&gt;</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
